[ADM] Plugins - ManaZeak/ManaZeak GitHub Wiki

ManaZeak features can be extended by installing plugins. To this day, here is the list of supported plugins for ManaZeak :

• MzkWorldMap, an interactive 3D globe (source).

Install a supported plugin

The plugin installation process is pretty simple, using mzk.sh script. For all following commands, replace <plugin-name> with one of the supported :

$ ./mzk.sh plugin install <plugin-name>

$ ./mzk.sh dev or $ ./mzk.sh prod*

To update the plugin to its latest master commit :

$ ./mzk.sh plugin update <plugin-name>

$ ./mzk.sh dev or $ ./mzk.sh prod*

To totally uninstall a plugin :

$ ./mzk.sh plugin uninstall <plugin-name>

$ ./mzk.sh dev or $ ./mzk.sh prod*

* Once the plugin has been installed/uninstalled/updated, you must bundle again the app assets, so webpack can automatically bundle plugin source files and assets into static. No further routing needs to be made, the plugin should be available in user interface.

Create a plugin

If you are not a developer, but yet have an awesome idea for a ManaZeak plugin, please contact [email protected], or open an issue to submit your idea. Otherwise, if you know s**t about code, there are several patterns to follow so the plugin can be easily integrated in ManaZeak.

Plugin basic structure

The plugin source code must be hosted on a git provider, or the source code must be available to be fetched so the plugin installation can be automated later.

Try the most to make your plugin without any HTML markup ; we haven't yet found a solution to smoothly embed custom HTML markup into ManaZeak final assets. Prefer an approach which consists of giving a DOM element to your plugin constructor so it can render in it.

About style files, please define an entry point from which all the style for the plugin will be set. Please use .scss so you can import all your required style files from this entry point ; this .scss entry point will be later used in the webpack.config.js to bundle style rules in ManaZeak /static/dist/css folder.

About JavaScript files, please define your component as an ES6 module. This will be the webpack JavaScript entry point ; it is important that this entry point imports all the plugin dependencies, this way, the plugin JavaScript source code can be bundled in one single file by ManaZeak, in /static/dist/js folder. Also, this entry point must attach itself to the window object so it can be globally available at runtime. Here is a basic example of your JavaScript entry point :

import 'all/the/lib/it/needs.js'
class MyPluginName { constructor() { console.log('Create MyPluginName instance'); } }
window.MyPluginName = MyPluginName;
export defatult MyPluginName;

Now that your plugin structure is done and that you have coded it, you must integrate it to ManaZeak (which may be the less fun part).

Plugin integration

If your plugin contains assets such as images, JSON files or any other format that is not style or script, you must write a python/bash script in your plugin repository that will copy its assets folder into a path sent as an argument ; this destination path must be /static/plugins so those assets are available to be fetched (the path is sent in ./mzk.sh, see next point). The plugin must also be able to uninstall or update itself, mainly by copying its new assets in the destination path. You can find an example which can be copy/pasted and edited to fit your plugin needs.

Edit ./mzk.sh file to add the plugin administration interface to the plugin command. For each install, uninstall and update subcommands, define how to copy the plugin source code in /plugins/, and execute the installation script of the plugin when copy is done. You can basically copy/paste the code used in ./mzk.sh for MzkWorldMap and replace with your plugin information.

Edit the webpack.config.js file to conditionally add your scss and js entry points. Again, you can copy /paste the MzkWorldMap code in it to implement yours.

Now you must define in /app/templates/index.html a template tag that will append your plugin bundles if plugin is installed on the instance. Add a test function in /app/templatetags/myPluginNameTags.py that returns your link and script HTML definition if plugin exists, '' otherwise.

Call now ./mzk.sh plugin install MyPluginName && ./mzk.sh dev ; at this point, you must be able to call new on your plugin component from anywhere in ManaZeak, since it has been attached to the window object. You can now make its integration in a custom view or else!

Feel free to contact [email protected] to seek help!